home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Think Class Libraries / PixelWorld classes 1.2 / CPixelWorld.info < prev    next >
Encoding:
Text File  |  1994-11-30  |  6.8 KB  |  164 lines  |  [TEXT/KAHL]
  1.                          The PixelWorld Class
  2.                          --------------------
  3.                              Version 1.2
  4.  
  5.                          SUPERCLASS = CBitMap
  6.  
  7.  
  8. 1) Description
  9.     
  10.     The CPixelWorld class is a subclass of CBitMap designed to maintain a 
  11.     color offscreen drawing environment using the standard conventions of 
  12.     Color QuickDraw.  An offscreen color graphics device (GDevice) and an 
  13.     offscreen color graphics port (CGrafPort) are used to maintain this 
  14.     offscreen world.  This implementation supports 1,2,4 and 8 bit pixel 
  15.     depths.  Pixel depths of 16 and 32 bits are currently not supported.  
  16.     
  17.     This implementation does not depend upon any 32-Bit QuickDraw features.  
  18.     Future versions of the CPixelWorld class will provide support for pixel 
  19.     depths of 16 and 32 bits, and for GWorlds under 32-Bit QuickDraw.  
  20.     
  21.     
  22. 2) Creating a blank PixelWorld
  23.     
  24.     A blank pixel world is created by calling the initialization method 
  25.     IPixelWorld with a pixel depth (aPixelDepth), a bounds rectangle 
  26.     (aBoundsRect), a handle to a color table (aColorTable), and NULL for 
  27.     the handle to the pixel image (aPixelImage).  You can pass any value 
  28.     for row bytes (aRowBytes) since the value will be ignored in this case.  
  29.     You should pass a color table handle (CTabHandle) in the aColorTable 
  30.     parameter.  The color table is copied and the copy is used for the 
  31.     offscreen world.  If aColorTable is NULL, then the default color table 
  32.     for the desired pixel depth will be used.  
  33.     
  34.                             *** WARNING ***
  35.     
  36.     If you request a pixel depth of one and Color QuickDraw is not 
  37.     available, then a blank offscreen world will be created as a standard 
  38.     BitMap with a non-color graphics port (GrafPort) using the CBitMap 
  39.     superclass.  If you request a pixel depth greater than one and Color 
  40.     QuickDraw is not available, the initialization method will fail.  To 
  41.     detect initialization failure call the method WorldIsOK, which 
  42.     returns the value of the instance variable worldIsOK.  WorldIsOK 
  43.     will return TRUE after successful initialization, and FALSE after 
  44.     initialization failure.  
  45.     
  46.     
  47. 3) Using an existing image to create a PixelWorld
  48.     
  49.     A world based on an existing color or grayscale image is created by 
  50.     calling the initialization method IPixelWorld with the pixel depth of 
  51.     the existing image (aPixelDepth), the bounds rectangle of the existing 
  52.     image (aBoundsRect), a color table for the existing image (aColorTable), 
  53.     and a handle to the pixels for the existing image (aPixelImage).  In 
  54.     this case, you must also pass a value for the row bytes of the pixel 
  55.     image (aRowBytes).  
  56.     
  57.                            *** IMPORTANT ***
  58.     
  59.     When you create an offscreen world based on an existing pixel image, 
  60.     IT IS YOUR RESPONSIBILITY TO DISPOSE OF YOUR PIXEL IMAGE.  Although 
  61.     CPixelWorld keeps its own handle to your pixel image in the instance 
  62.     variable worldPixels, it will not dispose of the pixel image.  In 
  63.     contrast, when you create a blank world by passing NULL for the 
  64.     aPixelImage parameter, CPixelWorld creates its own pixel image and it 
  65.     will dispose of this image when the offscreen world is destroyed by 
  66.     the Dispose method.  
  67.     
  68.     When you create your own pixel image for use with an offscreen world 
  69.     use a multiple of four for the row bytes of your pixel image.  The 
  70.     following formula will give a multiple of four for row bytes:  
  71.     
  72.         rowBytes = ((((long) width * pixelDepth) + 31) / 32) * 4;
  73.     
  74.     A multiple of four for row bytes will give optimal performance in calls 
  75.     to the QuickDraw function CopyBits and its related functions.  
  76.     
  77.                             *** WARNING ***
  78.     
  79.     When you create an offscreen world with an existing image that has a 
  80.     pixel depth greater than one, the initialization method will fail if 
  81.     Color QuickDraw is not available since there is no support for images 
  82.     with pixel depths greater than one without Color QuickDraw.  
  83.     
  84.     
  85. 4) Drawing to a PixelWorld
  86.     
  87.     If you need to draw directly to the offscreen world, you must bracket
  88.     all drawing with calls to BeginDrawing and EndDrawing.  This will 
  89.     set up the offscreen GDevice and CGrafPort for drawing.  The PixelWorld
  90.     will be sent a LockWorld( TRUE) message to make sure that the pixel 
  91.     image is anchored down and will not move when you invoke any QuickDraw
  92.     routines.  LockWorld( TRUE) locks the handle to the pixel image, and  
  93.     then loads the derefernced handle into the PixMap baseAddr pointers of 
  94.     both the offscreen GDevice and the offscreen CGrafPort.  
  95.     
  96.     
  97. 5) History
  98.     
  99.     • Version 1.0
  100.     
  101.         Date:            January 1, 1992
  102.         Author:            Vincent R. Vann, Jr.
  103.         Address:        1901 Brickell Ave, B-410, Miami, FL 33129 (USA)
  104.         Internet:        vvann@umbio.med.miami.edu
  105.         Compuserve:        76530,1242
  106.     
  107.     • Version 1.1
  108.     
  109.         Date:            January 28, 1992
  110.         Modified By:    Vincent R. Vann, Jr.
  111.         
  112.         Changes:
  113.         [
  114.             - CopyFrom and CopyTo methods were modified so that the foreground 
  115.               and background colors are set to black and white before calling 
  116.               CopyBits.  This ensures that the PixelWorld image is copied with 
  117.               the proper colors.  The foreground and background colors of the 
  118.               current CGrafPort are preserved by these methods. 
  119.         ]
  120.     
  121.     • Version 1.2
  122.     
  123.         Date:            June 15, 1992
  124.         Modified By:    Vincent R. Vann, Jr.
  125.         
  126.         Changes:
  127.         [
  128.             - added new instance variables saveFgColor and saveBgColor.
  129.             - implemented new methods SaveColors, RestoreColors, 
  130.               CopyFromColors, and CopyToColors.  
  131.             - changed CopyFrom and CopyTo methods to use these color routines.
  132.             - see comments for CopyFromColors and CopyToColors for information 
  133.               about how to colorize your image.  
  134.         ]
  135.     
  136.     
  137. 6) License Agreement
  138.     
  139.     All portions of this source code are property of Vincent R. Vann, Jr.
  140.     I, Vincent R. Vann, Jr., grant you the right to freely distribute this 
  141.     source code and to use all or part of this source code in all software  
  142.     including commercial, freeware, shareware and private applications.  
  143.     However, all software that uses any part of or all of this source code 
  144.     must display a copyright notice indicating that either all of or 
  145.     portions of this source code are used in the software.  I also grant 
  146.     you permission to alter and make improvements to this source code, but 
  147.     only if all modifications are returned to me by whatever means are 
  148.     available, either in written or electronic form.  You must also accept 
  149.     that I retain the right to include any part of your modifications or 
  150.     all of your modifications in future releases of this source code.  The 
  151.     description and version history sections of the *.info files may be 
  152.     ammended for documentation purposes.  This license agreement and the 
  153.     copyright notice below must be maintained intact and must be included 
  154.     with all distributions of this source code at all times.  
  155.     
  156.     
  157. 7) Copyright Notice
  158.     
  159.     This implementation is based in part on material copyrighted by 
  160.     Symantec Corporation and Apple Computer, Inc.  
  161.     
  162.     Copyright © 1992 Vincent R. Vann, Jr.  All rights reserved.  
  163.     
  164.